.TH std::pow,std::powf,std::powl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::pow,std::powf,std::powl \- std::pow,std::powf,std::powl

.SH Synopsis
   Defined in header <cmath>
   float       pow ( float base, float exp );

   double      pow ( double base, double exp );                 (until C++23)

   long double pow ( long double base, long double exp
   );
   /* floating-point-type */
                                                                (since C++23)
               pow ( /* floating-point-type */ base,            (constexpr since C++26)

                     /* floating-point-type */ exp )
   float       pow ( float base, int exp );

   double      pow ( double base, int exp );            \fB(1)\fP \fB(2)\fP \fI(until C++11)\fP

   long double pow ( long double base, int exp );
   float       powf( float base, float exp );               \fB(3)\fP \fI(since C++11)\fP
                                                                (constexpr since C++26)
   long double powl( long double base, long double exp      \fB(4)\fP \fI(since C++11)\fP
   );                                                           (constexpr since C++26)
   Additional overloads \fI(since C++11)\fP
   Defined in header <cmath>
   template< class Arithmetic1, class Arithmetic2 >

   /* common-floating-point-type */                         (A) (constexpr since C++26)

               pow ( Arithmetic1 base, Arithmetic2 exp
   );

   1-4) Computes the value of base raised to the power exp.
   The library provides overloads of std::pow for all cv-unqualified floating-point
   types as the type of the parameters base and exp.
   (since C++23)

   A) Additional overloads are provided for all other combinations of     \fI(since C++11)\fP
   arithmetic types.

.SH Parameters

   base - base as a floating-point or integer value
   exp  - exponent as a floating-point or integer value

.SH Return value

   If no errors occur, base raised to the power of exp (baseexp
   ), is returned.

   If a domain error occurs, an implementation-defined value is returned (NaN where
   supported).

   If a pole error or a range error due to overflow occurs, ±HUGE_VAL, ±HUGE_VALF, or
   ±HUGE_VALL is returned.

   If a range error occurs due to underflow, the correct result (after rounding) is
   returned.

.SH Error handling

   Errors are reported as specified in math_errhandling.

   If base is finite and negative and exp is finite and non-integer, a domain error
   occurs and a range error may occur.

   If base is zero and exp is zero, a domain error may occur.

   If base is zero and exp is negative, a domain error or a pole error may occur.

   If the implementation supports IEEE floating-point arithmetic (IEC 60559),

     * pow(+0, exp), where exp is a negative odd integer, returns +∞ and raises
       FE_DIVBYZERO.
     * pow(-0, exp), where exp is a negative odd integer, returns -∞ and raises
       FE_DIVBYZERO.
     * pow(±0, exp), where exp is negative, finite, and is an even integer or a
       non-integer, returns +∞ and raises FE_DIVBYZERO.
     * pow(±0, -∞) returns +∞ and may raise FE_DIVBYZERO.
     * pow(+0, exp), where exp is a positive odd integer, returns +0.
     * pow(-0, exp), where exp is a positive odd integer, returns -0.
     * pow(±0, exp), where exp is positive non-integer or a positive even integer,
       returns +0.
     * pow(-1, ±∞) returns 1.
     * pow(+1, exp) returns 1 for any exp, even when exp is NaN.
     * pow(base, ±0) returns 1 for any base, even when base is NaN.
     * pow(base, exp) returns NaN and raises FE_INVALID if base is finite and negative
       and exp is finite and non-integer.
     * pow(base, -∞) returns +∞ for any |base| < 1.
     * pow(base, -∞) returns +0 for any |base| > 1.
     * pow(base, +∞) returns +0 for any |base| < 1.
     * pow(base, +∞) returns +∞ for any |base| > 1.
     * pow(-∞, exp) returns -0 if exp is a negative odd integer.
     * pow(-∞, exp) returns +0 if exp is a negative non-integer or negative even
       integer.
     * pow(-∞, exp) returns -∞ if exp is a positive odd integer.
     * pow(-∞, exp) returns +∞ if exp is a positive non-integer or positive even
       integer.
     * pow(+∞, exp) returns +0 for any negative exp.
     * pow(+∞, exp) returns +∞ for any positive exp.
     * except where specified above, if any argument is NaN, NaN is returned.

.SH Notes

   C++98 added overloads where exp has type int on top of C pow(), and the return type
   of std::pow(float, int) was float. However, the additional overloads introduced in
   C++11 specify that std::pow(float, int) should return double. LWG issue 550 was
   raised to target this conflict, and the resolution is to removed the extra int exp
   overloads.

   Although std::pow cannot be used to obtain a root of a negative number, std::cbrt is
   provided for the common case where exp is 1/3.

   The additional overloads are not required to be provided exactly as (A). They only
   need to be sufficient to ensure that for their first argument num1 and second
   argument num2:

     * If num1 or num2 has type long double, then std::pow(num1, num2)
       has the same effect as std::pow(static_cast<long double>(num1),
                static_cast<long double>(num2)).
     * Otherwise, if num1 and/or num2 has type double or an integer type,
       then std::pow(num1, num2) has the same effect as                   (until C++23)
       std::pow(static_cast<double>(num1),
                static_cast<double>(num2)).
     * Otherwise, if num1 or num2 has type float, then std::pow(num1,
       num2) has the same effect as std::pow(static_cast<float>(num1),
                static_cast<float>(num2)).
   If num1 and num2 have arithmetic types, then std::pow(num1, num2) has
   the same effect as std::pow(static_cast</* common-floating-point-type
   */>(num1),
            static_cast</* common-floating-point-type */>(num2)), where
   /* common-floating-point-type */ is the floating-point type with the
   greatest floating-point conversion rank and greatest floating-point
   conversion subrank between the types of num1 and num2, arguments of    (since C++23)
   integer type are considered to have the same floating-point conversion
   rank as double.

   If no such floating-point type with the greatest rank and subrank
   exists, then overload resolution does not result in a usable candidate
   from the overloads provided.

.SH Example


// Run this code

 #include <cerrno>
 #include <cfenv>
 #include <cmath>
 #include <cstring>
 #include <iostream>
 // #pragma STDC FENV_ACCESS ON

 int main()
 {
     // typical usage
     std::cout << "pow(2, 10) = " << std::pow(2, 10) << '\\n'
               << "pow(2, 0.5) = " << std::pow(2, 0.5) << '\\n'
               << "pow(-2, -3) = " << std::pow(-2, -3) << '\\n';

     // special values
     std::cout << "pow(-1, NAN) = " << std::pow(-1, NAN) << '\\n'
               << "pow(+1, NAN) = " << std::pow(+1, NAN) << '\\n'
               << "pow(INFINITY, 2) = " << std::pow(INFINITY, 2) << '\\n'
               << "pow(INFINITY, -1) = " << std::pow(INFINITY, -1) << '\\n';

     // error handling
     errno = 0;
     std::feclearexcept(FE_ALL_EXCEPT);

     std::cout << "pow(-1, 1/3) = " << std::pow(-1, 1.0 / 3) << '\\n';
     if (errno == EDOM)
         std::cout << "    errno == EDOM " << std::strerror(errno) << '\\n';
     if (std::fetestexcept(FE_INVALID))
         std::cout << "    FE_INVALID raised\\n";

     std::feclearexcept(FE_ALL_EXCEPT);

     std::cout << "pow(-0, -3) = " << std::pow(-0.0, -3) << '\\n';
     if (std::fetestexcept(FE_DIVBYZERO))
         std::cout << "    FE_DIVBYZERO raised\\n";
 }

.SH Possible output:

 pow(2, 10) = 1024
 pow(2, 0.5) = 1.41421
 pow(-2, -3) = -0.125
 pow(-1, NAN) = nan
 pow(+1, NAN) = 1
 pow(INFINITY, 2) = inf
 pow(INFINITY, -1) = 0
 pow(-1, 1/3) = -nan
     errno == EDOM Numerical argument out of domain
     FE_INVALID raised
 pow(-0, -3) = -inf
     FE_DIVBYZERO raised

.SH See also

   sqrt               computes square root (\\(\\small{\\sqrt{x}}\\)
   sqrtf              √
   sqrtl              x)
   \fI(C++11)\fP            \fI(function)\fP
   \fI(C++11)\fP
   cbrt               computes cube root (\\(\\small{\\sqrt[3]{x}}\\)
   cbrtf              3
   cbrtl              √
   \fI(C++11)\fP            x)
   \fI(C++11)\fP            \fI(function)\fP
   \fI(C++11)\fP
                      computes square root of the sum of the squares of two
                      or three
                      \fI(since C++17)\fP given numbers (\\(\\scriptsize{\\sqrt{x^2+y^2}}\\)
                      √
   hypot              x2
   hypotf             +y2
   hypotl             )
   \fI(C++11)\fP            , (\\(\\scriptsize{\\sqrt{x^2+y^2+z^2}}\\)
   \fI(C++11)\fP            √
   \fI(C++11)\fP            x2
                      +y2
                      +z2
                      )
                      \fI(since C++17)\fP
                      \fI(function)\fP
   pow(std::complex)  complex power, one or both arguments may be a complex number
                      \fI(function template)\fP
                      applies the function std::pow to two valarrays or a valarray and
   pow(std::valarray) a value
                      \fI(function template)\fP
   C documentation for
   pow
